Custom Control Setting Constants0

TheNavCustomControlMessage data type defines constants that your application can pass in the selector parameter of the NavCustomControl function NavCustomControl to control various aspects of the active dialog box.

Constant descriptions

kNavCtlShowDesktop: Tells Navigation Services to change the browser list location to the desktop.
kNavCtlSortBy: Alerts Navigation Services that your application is setting a sort key in the browser list. In addition to the kNavCtlSortBy constant, your application passes one of the NavSortKeyField constants in the parms parameter of the function NavCustomControl . For a description of the NavSortKeyField constants, see File Sorting Constants.
kNavCtlSortOrder: Alerts Navigation Services that your application is setting sort order, either ascending or descending, in the browser list. In addition to passing the kNavCtlSortOrder constant, your application must pass one of the NavSortOrder constants in the parms parameter of the NavCustomControl function. For a description of the NavSortOrder constants, see Sort Order Constants.
kNavCtlScrollHome: Tells Navigation Services to scroll the browser to the top of the file list.
kNavCtlScrollEnd: Tells Navigation Services to scroll the browser to the bottom of the file list.
kNavCtlPageUp: Tells Navigation Services to scroll the browser up one page length as a result of the user clicking the scroll bar above the scroll box.
kNavCtlPageDown: Tells Navigation Services to scroll the browser down one page length as a result of the user clicking the scroll bar below the scroll box.
kNavCtlGetLocation: Tells Navigation Services to return the current location. When you specify this constant, the parms parameter of the NavCustomControl function returns a pointer to an AEDesc structure describing the current location. For more information on parsing AEDesc structures, see Obtaining Object Descriptions.
kNavCtlSetLocation: Tells Navigation Services that your application wishes to set the location being viewed in the browser list. In addition to specifying the kNavCtlSetLocation constant, your application passes a pointer to an AEDesc structure describing the new location in the parms parameter of the NavCustomControl function.
kNavCtlGetSelection: Tells Navigation Services to return the selected item or items in the browser. When you specify this constant, the parms parameter of the NavCustomControl function returns a pointer to an AEDescList structure describing the selected item(s). For more information on parsing AEDescList structures, see Obtaining Object Descriptions. If the user deselects the current selection, the AEDescList returned by Navigation Services contains an empty reference. You can account for this case by using the function AECountItems and checking for a zero count.
kNavCtlSetSelection: Tells Navigation Services to change the browser list selection. In addition to specifying the kNavCtlSetSelection constant, your application must pass a pointer to an AEDescList structure describing the selection in the parms parameter of the NavCustomControl function. If you want to deselect the current selection without making a new selection, pass NULL for the pointer.
kNavCtlShowSelection: Tells Navigation Services to make the current selection visible in the browser list if the selection has been scrolled out of sight by the user.
kNavCtlOpenSelection: Tells Navigation Services to open the current selection.
kNavCtlEjectVolume: Tells Navigation Services to eject a volume. In addition to specifying this constant, you must pass a pointer to the volume reference number (vRefNum ) of the volume to be ejected in the parms parameter of the NavCustomControl function.
kNavCtlNewFolder: Tells Navigation Services to create a new folder in the current location. In addition to specifying the kNavCtlNewFolder constant, your application passes a string representing the name of the new folder in the parms parameter of the NavCustomControl function.
kNavCtlCancel: Tells Navigation Services to dismiss the Open or Save dialog box as if the user had pressed the Cancel button.
kNavCtlAccept: Tells Navigation Services to close the Open or Save dialog box as if the user had pressed the Open or Save button. Navigation Services does not act on this constant if there is no current selection.
kNavCtlIsPreviewShowing: Asks Navigation Services if the preview area is currently available. If you specify this constant, Navigation Services returns a pointer to a Boolean value of true in the parms parameter of the NavCustomControl function if the preview area is available.
kNavCtlAddControl: Tells Navigation Services to add one application-defined control to Open or Save dialog boxes. In addition to sending this message, your application passes a control handle in the parms parameter of the NavCustomControl function. Design the control in local coordinates.

IMPORTANT

To avoid any unnecessary flickering or redrawing, ensure the control is initially invisible before specifying this constant. You may set the control to visible after Navigation Services supplies the kNavCBStart constant, described in Event Message Constants , in the param field of the structure of type NavCBRec . If the user resizes the dialog box, your application must move the control because it is not maintained by Navigation Services. If you use the kNavCtlAddControlList constant (described next) and you supply a 'DITL' resource, you avoid the need to move the control yourself.

kNavCtlAddControlList: Tells Navigation Services to add a list of application-defined dialog box items to Open or Save dialog boxes. In addition to specifying this constant, your application must pass a handle to a dialog box item list or 'DITL' resource in the parms parameter of the NavCustomControl function. Design the'DITL' resource in local coordinates. Navigation Services will add the custom items relative to the upper left corner of the customization area. If the user resizes the dialog box, your custom items are moved automatically.
kNavCtlGetFirstControlID: Asks Navigation Services to help you identify the first custom control in the dialog box, in order to determine which custom control item was selected by the user. The parms parameter of the NavCustomControl function returns a pointer to a 16-bit integer that indicates the item number of the first custom control. In your event-handling function, use the Dialog Manager function FindDialogItem to find out which item was selected. The FindDialogItem function returns 0 for the first item, 1 for the second and so on. To get the proper item number, add 1 to the FindDialogItem function result. The Open or Save dialog box's standard controls precede yours, so use the formula (itemHit - yourFirstItem + 1) to determine which of your items was selected. Your application should not depend on any hardcoded value for the number of items, since this value is likely to change in the future.

IMPORTANT

Take care to test the result from FindDialogItem to ensure that it describes a control that you defined. Your application must not respond to any controls that do not belong to it.

kNavCtlSelectCustomType: Tells Navigation Services to set one of your custom menu items in the Show pop-up menu or the Format pop-up menu as the default selection. This is useful if you want to override the default pop-up menu selection. In addition to specifying this constant, pass a pointer to a structure of type NavMenuItemSpec in the parms parameter of the NavCustomControl function. This structure describes the item you wish to have selected. For more information on providing custom menu items, see Customizing Type Pop-up Menus.
kNavCtlSelectAllType: Tells Navigation Services to override the default menu item in the Type pop-up menu. By specifying one of the NavPopupMenuItem constants, described in Menu Item Selection Constants , in the parms parameter of the function NavCustomControl , you can set the default item to All <AppName> Documents, All Readable Documents or All Documents.
kNavCtlGetEditFileName: Tells Navigation Services to return the name of the file to be saved by the function NavPutFile . This would be useful if you wanted to automatically add an extension to the filename, for example. When you send this message, the parms parameter of the NavCustomControl function returns a StringPtr to a Pascal string containing the filename.
kNavCtlSetEditFileName: Tells Navigation Services that your application wishes to set the name of the file to be saved by the function NavPutFile . Your application normally specifies the KNavCtlSetEditFileName constant after modifying the filename obtained by specifying the kNavCtlGetEditFileName constant. In addition to specifying the kNavCtlSetEditFileName constant, your application must pass a StringPtr to a Pascal string containing the filename in the parms parameter of the NavCustomControl function.
kNavCtlSelectEditFileName: (Navigation Services 1.1 ONLY ) Tells Navigation Services to display the name of the file to be saved by the function NavPutFile with some or all of the filename string highlighted for selection. In addition to specifying the kNavCtlSelectEditFileName constant, your application passes a Control Manager structure of type ControlEditTextSelectionRec in the parms parameter of the NavCustomControl function in order to specify which part of the filename string to highlight. For more information on the ControlEditTextSelectionRec structure, see Mac OS 8 Toolbox Reference .